/**
* gdk_pixdata_serialize:
- * @pixdata: A valid GdkPixdata structure to serialize
- * @stream_length_p: Location to store the resulting stream length in
+ * @pixdata: a valid #GdkPixdata structure to serialize.
+ * @stream_length_p: location to store the resulting stream length in.
*
- * Serialize a #GdkPixdata structure into a byte stream.
- * The byte stream consists of a straight forward write out of the
- * #GdkPixdata fields in network byte order, plus the pixel_data
+ * Serializes a #GdkPixdata structure into a byte stream.
+ * The byte stream consists of a straightforward writeout of the
+ * #GdkPixdata fields in network byte order, plus the @pixel_data
* bytes the structure points to.
*
* Return value: A newly-allocated string containing the serialized
- * GdkPixdata structure
+ * #GdkPixdata structure.
**/
guint8* /* free result */
gdk_pixdata_serialize (const GdkPixdata *pixdata,
/**
* gdk_pixdata_deserialize:
- * @pixdata: A GdkPixdata structure to be filled in
- * @stream_length: Length of the stream used for deserialization
- * @stream: Stream of bytes containing a serialized pixdata structure
- * @error: GError location to indicate failures (maybe NULL to ignore errors)
+ * @pixdata: a #GdkPixdata structure to be filled in.
+ * @stream_length: length of the stream used for deserialization.
+ * @stream: stream of bytes containing a serialized #GdkPixdata structure.
+ * @error: #GError location to indicate failures (maybe %NULL to ignore errors).
*
- * Deserialize (reconstruct) a #GdkPixdata structure from a byte stream.
- * The byte stream consists of a straight forward write out of the
- * #GdkPixdata fields in network byte order, plus the pixel_data
+ * Deserializes (reconstruct) a #GdkPixdata structure from a byte stream.
+ * The byte stream consists of a straightforward writeout of the
+ * #GdkPixdata fields in network byte order, plus the @pixel_data
* bytes the structure points to.
- * The pixdata contents are reconstructed byte by byte and are checked
+ * The @pixdata contents are reconstructed byte by byte and are checked
* for validity. This function may fail with %GDK_PIXBUF_CORRUPT_IMAGE
- * or %GDK_PIXBUF_ERROR_UNKNOWN_TYPE
+ * or %GDK_PIXBUF_ERROR_UNKNOWN_TYPE.
*
- * Return value: Upon successfull deserialization %TRUE is returned,
- * %FALSE otherwise
+ * Return value: Upon successful deserialization %TRUE is returned,
+ * %FALSE otherwise.
**/
gboolean
gdk_pixdata_deserialize (GdkPixdata *pixdata,
return bp;
}
+/**
+ * gdk_pixdata_from_pixbuf:
+ * @pixdata: a #GdkPixdata to fill.
+ * @pixbuf: the data to fill @pixdata with.
+ * @use_rle: whether to use run-length encoding for the pixel data.
+ *
+ * Converts a #GdkPixbuf to a #GdkPixdata. If @use_rle is %TRUE, the
+ * pixel data is run-length encoded into newly-allocated memory and a
+ * pointer to that memory is returned.
+ *
+ * Returns: If @ure_rle is %TRUE, a pointer to the newly-allocated memory
+ * for the run-length encoded pixel data, otherwise %NULL.
+ **/
gpointer
gdk_pixdata_from_pixbuf (GdkPixdata *pixdata,
const GdkPixbuf *pixbuf,
return free_me;
}
+/**
+ * gdk_pixbuf_from_pixdata:
+ * @pixdata: a #GdkPixdata to convert into a #GdkPixbuf.
+ * @copy_pixels: whether to copy raw pixel data; run-length encoded
+ * pixel data is always copied.
+ * @error: location to store possible errors.
+ *
+ * Converts a #GdkPixdata to a #GdkPixbuf. If @copy_pixels is %TRUE or
+ * if the pixel data is run-length-encoded, the pixel data is copied into
+ * newly-allocated memory; otherwise it is reused.
+ *
+ * Returns: a new #GdkPixbuf.
+ **/
GdkPixbuf*
gdk_pixbuf_from_pixdata (const GdkPixdata *pixdata,
gboolean copy_pixels,
APPEND (gstring, " } } while (0)\n");
}
+/**
+ * gdk_pixdata_to_csource:
+ * @pixdata: a #GdkPixdata to convert to C source.
+ * @name: used for naming generated data structures or macros.
+ * @dump_type: a #GdkPixdataDumpType determining the kind of C
+ * source to be generated.
+ *
+ * Generates C source code suitable for compiling images directly
+ * into programs.
+ *
+ * Gtk+ ships with a program called gdk-pixbuf-csource which offers
+ * a cmdline interface to this functions.
+ *
+ * Returns: a newly-allocated string containing the C source form
+ * of @pixdata.
+ **/
GString*
gdk_pixdata_to_csource (GdkPixdata *pixdata,
const gchar *name,
* ship a program with images, but don't want to depend on any
* external files.
*
- * Gtk+ ships with a program called gdk-pixbuf-csource which allowes
- * for conversion of #GdkPixbufs into such a inline reprentation.
+ * Gtk+ ships with a program called gdk-pixbuf-csource which allows
+ * for conversion of #GdkPixbufs into such a inline representation.
* In almost all cases, you should pass the --raw flag to
* gdk-pixbuf-csource. A sample invocation would be:
*
extern "C" {
#endif /* __cplusplus */
-
+/**
+ * GDK_PIXBUF_MAGIC_NUMBER:
+ *
+ * Magic number for #GdkPixdata structures.
+ **/
#define GDK_PIXBUF_MAGIC_NUMBER (0x47646b50) /* 'GdkP' */
+/**
+ * GdkPixdataType:
+ * @GDK_PIXDATA_COLOR_TYPE_RGB: each pixel has red, green and blue samples.
+ * @GDK_PIXDATA_COLOR_TYPE_RGBA: each pixel has red, green and blue samples
+ * and an alpha value.
+ * @GDK_PIXDATA_COLOR_TYPE_MASK: mask for the colortype flags of the enum.
+ * @GDK_PIXDATA_SAMPLE_WIDTH_8: each sample has 8 bits.
+ * @GDK_PIXDATA_SAMPLE_WIDTH_MASK: mask for the sample width flags of the enum.
+ * @GDK_PIXDATA_ENCODING_RAW: the pixel data is in raw form.
+ * @GDK_PIXDATA_ENCODING_RLE: the pixel data is run-length encoded. Runs may
+ * be up to 127 bytes long; their length is stored in a single byte
+ * preceding the pixel data for the run. If a run is constant, its length
+ * byte has the high bit set and the pixel data consists of a single pixel
+ * which must be repeated.
+ * @GDK_PIXDATA_ENCODING_MASK: mask for the encoding flags of the enum.
+ *
+ * An enumeration containing three sets of flags for a #GdkPixdata struct:
+ * one for the used colorspace, one for the width of the samples and one
+ * for the encoding of the pixel data.
+ **/
typedef enum
{
/* colorspace + alpha */
GDK_PIXDATA_ENCODING_MASK = 0x0f << 24
} GdkPixdataType;
+/**
+ * GdkPixdata:
+ * @magic: magic number. A valid #GdkPixdata structure must have
+ * #GDK_PIXBUF_MAGIC_NUMBER here.
+ * @length: less than 1 to disable length checks, otherwise
+ * #GDK_PIXDATA_HEADER_LENGTH + length of @pixel_data.
+ * @pixdata_type: information about colorspace, sample width and
+ * encoding, in a #GdkPixdataType.
+ * @rowstride: padding used in @pixel_data or 0 to indicate no padding.
+ * @width: the width.
+ * @height: the height.
+ * @pixel_data: @width x @height pixels, encoded according to @pixdata_type
+ * and @rowstride.
+ *
+ * A #GdkPixdata contains pixbuf information in a form suitable for
+ * serialization and streaming.
+ **/
typedef struct _GdkPixdata GdkPixdata;
struct _GdkPixdata
{
guint32 height;
guint8 *pixel_data;
};
+
+/**
+ * GDK_PIXDATA_HEADER_LENGTH:
+ *
+ * The length of a #GdkPixdata structure without the @pixel_data pointer.
+ **/
#define GDK_PIXDATA_HEADER_LENGTH (4 + 4 + 4 + 4 + 4 + 4)
/* the returned stream is plain htonl of GdkPixdata members + pixel_data */
GdkPixbuf* gdk_pixbuf_from_pixdata (const GdkPixdata *pixdata,
gboolean copy_pixels,
GError **error);
+/**
+ * GdkPixdataDumpType:
+ * @GDK_PIXDATA_DUMP_PIXDATA_STREAM: Generate pixbuf data stream (a single
+ * string containing a serialized #GdkPixdata structure in network byte
+ * order).
+ * @GDK_PIXDATA_DUMP_PIXDATA_STRUCT: Generate #GdkPixdata structure (needs
+ * the #GdkPixdata structure definition from gdk-pixdata.h).
+ * @GDK_PIXDATA_DUMP_MACROS: Generate <function>*_ROWSTRIDE</function>,
+ * <function>*_WIDTH</function>, <function>*_HEIGHT</function>,
+ * <function>*_BYTES_PER_PIXEL</function> and
+ * <function>*_RLE_PIXEL_DATA</function> or <function>*_PIXEL_DATA</function>
+ * macro definitions for the image.
+ * @GDK_PIXDATA_DUMP_GTYPES: Generate GLib data types instead of
+ * standard C data types.
+ * @GDK_PIXDATA_DUMP_CTYPES: Generate standard C data types instead of
+ * GLib data types.
+ * @GDK_PIXDATA_DUMP_STATIC: Generate static symbols.
+ * @GDK_PIXDATA_DUMP_CONST: Generate const symbols.
+ * @GDK_PIXDATA_DUMP_RLE_DECODER: Provide a <function>*_RUN_LENGTH_DECODE(image_buf, rle_data, size, bpp)</function>
+ * macro definition to decode run-length encoded image data.
+ *
+ * An enumeration which is used by gdk_pixdata_to_csource() to
+ * determine the form of C source to be generated. The three values
+ * @GDK_PIXDATA_DUMP_PIXDATA_STREAM, @GDK_PIXDATA_DUMP_PIXDATA_STRUCT
+ * and @GDK_PIXDATA_DUMP_MACROS are mutually exclusive, as are
+ * @GDK_PIXBUF_DUMP_GTYPES and @GDK_PIXBUF_DUMP_CTYPES. The remaining
+ * elements are optional flags that can be freely added.
+ **/
typedef enum
{
/* type of source to save */
projects / gtk4.git / commitdiff